Skip to content

Section 4.2 is unclear #371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Section 4.2 is unclear #371

wants to merge 2 commits into from

Conversation

njr-11
Copy link
Contributor

@njr-11 njr-11 commented Apr 28, 2025 •
edited
Loading

While answering a question from a user, I read through section 4.2 on Customizing Property Order and JsonbPropertyOrder Javadoc regarding whether original property names vs customized property names are used in determining the order.

Section 4.2 is unclear because in one place it defers to JsonbPropertyOrder,

To customize the order of serialized properties only for one specific type, JSON Binding provides jakarta.json.bind.annotation.JsonbPropertyOrder annotation. Order specified by JsonbPropertyOrder annotation overrides order specified by PropertyOrderStrategy.

but immediately after that states that The order is applied to already renamed properties as stated in 4.1, which would contradict JsonbPropertyOrder's statement that Names must correspond to original names defined in Java class before any customization applied.

After rereading these seemingly conflicting statements several times over, I finally realized that the line at the end of section 4.2 isn't meant to apply to JsonbPropertyOrder that was discussed immediately before it. Instead, it is intended only for PropertyOrderStrategy.

The PR adds clarification to that line of section 4.2 (first commit). A second commit adds a few grammar corrections that I noticed in that same section. If anyone doesn't want the grammar corrections part, just let me know and I'll remove that commit.

@njr-11 njr-11 added the documentation Involves the spec or javadocs label Apr 28, 2025
@njr-11 njr-11 added this to the 3.1 milestone Apr 28, 2025
@sean-leichtle
Copy link

I'm quite new to Jsonb, so apologies in advance if I've misunderstood something, but annotating a record with @JsonbPropertyOrder doesn't seem to work unless the individual fields in the record are annotated with @JsonbProperty.

That is, the following is deserialized correctly in the order specified by @JsonbPropertyOrder:

@JsonbPropertyOrder({
        "getCommand",
        "getUserName",
})
public record NetworkMessage(
        @JsonbProperty("getCommand") Command getCommand,
        @JsonbProperty("getUserName") String getUserName
) {
    @JsonbCreator
    public NetworkMessage { }
}

The following is not correctly deserialized:

@JsonbPropertyOrder({
        "getCommand",
        "getUserName",
})
public record NetworkMessage(
        Command getCommand,
        String getUserName
) {
    @JsonbCreator
    public NetworkMessage { }
}

I realize records are a special case, but it seems either the end of 4.2 should be amended to read A PropertyOrderStrategy as well as a PropertyOrder used to annotate a record determines the order based on the already renamed properties that have been customized according to the rules outlined under section 4.1. or the JsonbPropertyOrderstatement should be changed to Except in the case of records, names must correspond to original names defined in Java class before any customization applied.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
documentation Involves the spec or javadocs
Projects
None yet
Milestone
3.1
Development

Successfully merging this pull request may close these issues.
2 participants
@njr-11 @sean-leichtle